Writing Health Category Samples#

The Scripting app allows you to write categorical health data to Apple HealthKit using the HealthCategorySample class and the Health.saveCategorySample() method. Category samples represent discrete health-related events or conditions, such as sleep stages, mindful sessions, menstrual flow, ovulation test results, and more.

This guide describes how to create and save a HealthCategorySample.

Prerequisites#

• Confirm that HealthKit is available on the device:

  1if (!Health.isHealthDataAvailable) {
  2  throw new Error("Health data is not available on this device.")
  3}

• Ensure the script has the required permission for the target category type. The Scripting app will automatically request authorization if needed when saving.

1. Create a HealthCategorySample#

Use HealthCategorySample.create() to construct a new category sample.

Parameters#

• type: A HealthCategoryType string (e.g., "sleepAnalysis", "mindfulSession", "menstrualFlow", etc.).
• startDate: The beginning of the time interval that the event applies to (JavaScript Date).
• endDate: The end of the event’s time interval (JavaScript Date).
• value: The integer value representing the state of the category. You must use the corresponding enum value based on the type.
• metadata (optional): An optional metadata object describing additional attributes.

Value Mapping#

The value must be one of the pre-defined category values. For example:

• For "sleepAnalysis", use the HealthCategoryValueSleepAnalysis enum:

  • HealthCategoryValueSleepAnalysis.asleepCore
  • HealthCategoryValueSleepAnalysis.awake
  • etc.

• For "menstrualFlow", use HealthCategoryValueSeverity:

  • HealthCategoryValueSeverity.mild, moderate, severe, etc.

Refer to each category type’s enum definition for valid values.

Example#

1const sample = HealthCategorySample.create({
2  type: "sleepAnalysis",
3  startDate: new Date("2025-07-03T23:00:00"),
4  endDate: new Date("2025-07-04T07:00:00"),
5  value: HealthCategoryValueSleepAnalysis.asleepCore,
6  metadata: {
7    source: "ScriptingApp"
8  }
9})
10
11if (!sample) {
12  throw new Error("Failed to create HealthCategorySample.")
13}

2. Save the Category Sample#

Use Health.saveCategorySample() to save the created sample to HealthKit.

1await Health.saveCategorySample(sample)

If saving fails (e.g., due to permission denial), the promise will reject with an error.

Full Example#

1async function writeSleepData() {
2  const sample = HealthCategorySample.create({
3    type: "sleepAnalysis",
4    startDate: new Date("2025-07-03T23:00:00"),
5    endDate: new Date("2025-07-04T07:00:00"),
6    value: HealthCategoryValueSleepAnalysis.asleepCore,
7  })
8
9  if (!sample) {
10    console.error("Failed to create sample.")
11    return
12  }
13
14  try {
15    await Health.saveCategorySample(sample)
16    console.log("Sleep data saved successfully.")
17  } catch (err) {
18    console.error("Error saving sample:", err)
19  }
20}
21
22writeSleepData()

Notes#

• The value must be a valid enum for the selected type, or the creation will fail.
• startDate and endDate define the time range the event applies to — e.g., a sleep session or a mindful moment.
• Metadata is optional but can be useful for tagging data source or context.